docs: add mixed marketplace skills guide by neubig · Pull Request #375 · OpenHands/docs

neubig · 2026-03-04T20:00:18Z

Summary

Updates marketplace schema documentation to clarify that both repo and marketplace fields are required.

Closes #374

Details

The marketplace JSON schema requires both fields:

repo: The GitHub repository URL (e.g., https://github.com/OpenHands/extensions)
marketplace: Path to marketplace JSON within the repo (e.g., marketplaces/default.json)

This clarification helps users correctly configure custom skill repositories.

Testing

Documentation change - no unit tests applicable.

CI checks:

Mintlify validation: ✅ PASSED
Link check: ✅ PASSED

Evidence

Verification link: View conversation

Live command output against the SDK behavior documented here:

$ HOME=/tmp/sdk-evidence-home uv run python - <<'PY'
from openhands.sdk.context.skills.skill import load_public_skills
repo_url = 'file:///tmp/marketplace-evidence-repo'
custom = sorted(
    skill.name
    for skill in load_public_skills(
        repo_url=repo_url,
        branch='main',
        marketplace_path='marketplaces/custom.json',
    )
)
all_skills = sorted(
    skill.name
    for skill in load_public_skills(
        repo_url=repo_url,
        branch='main',
        marketplace_path=None,
    )
)
print('custom_marketplace', custom)
print('all_public_skills', all_skills)
PY
custom_marketplace ['git', 'internal-only']
all_public_skills ['docker', 'git', 'internal-only']

This is the behavior the docs are clarifying: users need both a repository source and a marketplace path to load a custom curated marketplace from a skills repo.

Checklist

Documentation accurate
CI checks passing
Live CLI evidence added
Cross-referenced to SDK implementation PR

Add documentation for combining local and remote skills from OpenHands extensions repository. Includes: - Use case explanation - Loading pattern comparison - Full example code reference - Local skill creation guide - Precedence rules Co-authored-by: openhands <openhands@all-hands.dev>

sdk/guides/mixed-marketplace-skills.mdx

enyst

Reviewed latest changes. I left one inline suggestion to clarify that OpenHands uses the Claude Code plugin marketplace schema as a filter list for public skills, while local skills are merged separately. Otherwise LGTM.

Co-authored-by: openhands <openhands@all-hands.dev>

enyst · 2026-03-05T13:06:44Z

OpenHands-GPT-5.2 here. I pushed a docs update clarifying that marketplace.json uses the Claude plugin schema plus the OpenHands skills[] extension, and that marketplace entries point to skill directories while local skills are merged separately. Commit: 32e23db.

The example was updated to use skills/ instead of local_skills/ to follow the standard plugin structure. Co-authored-by: openhands <openhands@all-hands.dev>

Address review feedback: Clarify that marketplace.json plugin entry names are used as a filter list for loading public skills, not defining skills directly. Local skills are merged separately from local_skills/ directory. Co-authored-by: openhands <openhands@all-hands.dev>

all-hands-bot

Taste Rating: 🟡 Acceptable - Good content but has clarity gaps that will confuse users.

Key Issue: The guide mentions concepts (marketplace.json, Claude Code plugin schema) that are never explained or demonstrated, while the example code uses a completely different approach. This creates a disconnect between what users read and what they learn.

sdk/guides/mixed-marketplace-skills.mdx

neubig · 2026-03-07T13:34:39Z

Moved to draft - Evidence needs live run

The Evidence section currently shows a code snippet, but not actual output from running it.

Since this is a documentation PR clarifying schema requirements, acceptable evidence would be:

Actually running the code and showing it works, OR
Cross-referencing to SDK PR #2253 which already demonstrates this functionality (currently mentioned but not clearly stated as the evidence)

Please either:

Add actual command output showing the schema validation working
Or clarify that the evidence is the successful tests in PR #2253

all-hands-bot

Taste Rating: 🟡 Acceptable - Good content but has clarity gaps that will confuse users.

Key Issue: The guide mentions concepts (marketplace.json, Claude Code plugin schema) that are never explained or demonstrated, while the example code uses a completely different approach. This creates a disconnect between what users read and what they learn.

sdk/guides/mixed-marketplace-skills.mdx

Co-authored-by: openhands <openhands@all-hands.dev>

all-hands-bot

Taste Rating: 🟡 Acceptable - Working code but has documentation gaps that will confuse users.

Key Issue: The guide shows the .plugin/marketplace.json format but never demonstrates how to load from it or what API consumes it. Users will wonder "how do I actually USE this file?" Additionally, the PR description mentions repo and marketplace parameters that don't appear in the guide itself.

all-hands-bot · 2026-03-26T10:40:57Z

sdk/guides/mixed-marketplace-skills.mdx

+
+The `.plugin/marketplace.json` file follows the Claude Code plugin marketplace schema, with an OpenHands extension for direct `skills[]` entries. A minimal mixed example looks like this:
+
+```json
+{
+  "name": "mixed-skills-marketplace",
+  "plugins": [],
+  "skills": [
+    {
+      "name": "greeting-helper",
+      "source": "./local_skills/greeting-helper",
+      "description": "A local greeting skill"
+    },
+    {
+      "name": "github",
+      "source": "https://github.com/OpenHands/extensions/blob/main/skills/github",
+      "description": "GitHub best practices from OpenHands/extensions"
+    }
+  ]
+}
+```
+
+That file is the repository-managed configuration that expresses the mixed marketplace itself.
+
+The code example below focuses on the two underlying loader APIs (`load_skills_from_dir()` and `load_public_skills()`) so you can see exactly what each source contributes. In other words:
+
+- `load_skills_from_dir(local_skills_dir)` reads local `SKILL.md` files from your repository.
+- `load_public_skills()` reads from the SDK's default OpenHands/extensions marketplace.
+- `.plugin/marketplace.json` is the place where you would encode an equivalent curated mix when you want the repository to own that marketplace configuration.


🟠 Important - Missing Usage Documentation: You show the marketplace.json format and say it's "where you would encode an equivalent curated mix," but you never show HOW to load from it.

What's missing:

What API function loads from .plugin/marketplace.json?

Is it auto-detected by some higher-level API?

Or do you pass it to load_public_skills(marketplace_path='.plugin/marketplace.json')?

The problem: This is like showing a config file format without explaining what program reads it. Users will complete this guide and ask "OK, I created the file... now what?"

Fix options:

Add a code example showing how to load from a custom marketplace.json file

Or clarify that this file is auto-detected (if true) and explain when/how

Or remove this section entirely and focus purely on the manual loader APIs

Right now you're introducing a concept without completing the explanation.

all-hands-bot · 2026-03-26T10:40:57Z

sdk/guides/mixed-marketplace-skills.mdx

+    # Load public skills from the OpenHands extensions repository.
+    # This call uses the SDK's default OpenHands/extensions marketplace,
+    # not the `.plugin/marketplace.json` file shown above.
+    public_skills = load_public_skills()


🟡 Suggestion - Incomplete API Documentation: Your PR description's evidence shows load_public_skills() accepts repo_url, branch, and marketplace_path parameters:

load_public_skills( repo_url=repo_url, branch='main', marketplace_path='marketplaces/custom.json', )

But this guide shows it called with no arguments and never mentions these parameters.

If these parameters are relevant to the "mixed marketplace" use case, document them. For example:

Show how to load from a custom marketplace in a custom repo

Explain the difference between the default marketplace vs. custom marketplace

If they're NOT relevant to this specific guide, that's fine—but then the PR description is misleading about what this guide demonstrates.

all-hands-bot · 2026-03-26T10:40:57Z

sdk/guides/mixed-marketplace-skills.mdx

+| `load_skills_from_dir()` | Local directory | Project-specific skills |
+| `load_public_skills()` | OpenHands/extensions | Community skills filtered by a marketplace |
+


🟢 Nit - Potentially Misleading Description: Table says load_public_skills() loads "Community skills filtered by a marketplace" but the example (line 173) calls it with no arguments, so it uses the DEFAULT marketplace.

Consider clarifying: "Community skills from default marketplace" or "Community skills (uses SDK default marketplace when called without arguments)"

mintlify bot deployed to staging March 4, 2026 20:01 View deployment

neubig mentioned this pull request Mar 4, 2026

feat(examples): add mixed marketplace skills example OpenHands/software-agent-sdk#2299

Closed

enyst reviewed Mar 5, 2026

View reviewed changes

sdk/guides/mixed-marketplace-skills.mdx Outdated Show resolved Hide resolved

enyst reviewed Mar 5, 2026

View reviewed changes

docs: clarify marketplace skill filtering

32e23db

Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging March 5, 2026 13:07 View deployment

fix: update docs to reference skills/ directory

a5a4609

The example was updated to use skills/ instead of local_skills/ to follow the standard plugin structure. Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging March 5, 2026 14:02 View deployment

neubig requested a review from enyst March 5, 2026 14:02

mintlify bot deployed to staging March 7, 2026 02:00 View deployment

neubig marked this pull request as ready for review March 7, 2026 02:02

neubig requested a review from xingyaoww as a code owner March 7, 2026 02:02

all-hands-bot reviewed Mar 7, 2026

View reviewed changes

sdk/guides/mixed-marketplace-skills.mdx Show resolved Hide resolved

sdk/guides/mixed-marketplace-skills.mdx Show resolved Hide resolved

sdk/guides/mixed-marketplace-skills.mdx Outdated Show resolved Hide resolved

sdk/guides/mixed-marketplace-skills.mdx Show resolved Hide resolved

neubig marked this pull request as draft March 7, 2026 13:34

Clarify mixed marketplace guide flow

8607df1

mintlify bot deployed to staging March 7, 2026 20:34 View deployment

neubig marked this pull request as ready for review March 7, 2026 20:41

all-hands-bot reviewed Mar 7, 2026

View reviewed changes

sdk/guides/mixed-marketplace-skills.mdx Show resolved Hide resolved

sdk/guides/mixed-marketplace-skills.mdx Show resolved Hide resolved

sdk/guides/mixed-marketplace-skills.mdx Show resolved Hide resolved

sdk/guides/mixed-marketplace-skills.mdx Outdated Show resolved Hide resolved

enyst reviewed Mar 8, 2026

View reviewed changes

sdk/guides/mixed-marketplace-skills.mdx Outdated Show resolved Hide resolved

Apply suggestion from @enyst

40b1924

mintlify bot deployed to staging March 8, 2026 05:03 View deployment

neubig marked this pull request as draft March 19, 2026 04:37

Clarify mixed marketplace filtering docs

1aa85ed

Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging March 26, 2026 10:33 View deployment

neubig marked this pull request as ready for review March 26, 2026 10:37

all-hands-bot reviewed Mar 26, 2026

View reviewed changes

		\| `load_skills_from_dir()` \| Local directory \| Project-specific skills \|
		\| `load_public_skills()` \| OpenHands/extensions \| Community skills filtered by a marketplace \|

Conversation

neubig commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

Testing

Evidence

Checklist

Uh oh!

Uh oh!

enyst left a comment

Choose a reason for hiding this comment

Uh oh!

enyst commented Mar 5, 2026

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

neubig commented Mar 7, 2026

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

all-hands-bot Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

neubig commented Mar 4, 2026 •

edited

Loading